pass
Type
control structure
Summary
Stops the current handler and passes the message to the next object in the message path.
Syntax
pass <messageName> [to top]
Description
Use the pass control structure to end a handler while letting the message continue along the message path.
Form: The pass statement appears on a line by itself, anywhere inside a handler.
When the pass control structure is executed, any remaining statements in the handler are skipped. Hence, the pass control structure is usually used either at the end of a handler or within an if control structure.
Use the pass control structure at the end of a handler to make sure that objects further up the message path, or LiveCode itself, receive the message. For example, if a stack's script contains a closeCard handler that does housekeeping tasks, and a particular card needs to perform additional tasks if the stack is closed when on that card, the card's closeCard handler can perform those additional tasks, and then use the pass control structure to let the closeCard handler in the stack's script receive the message and be executed. The following example demonstrates the idea:
on closeCard -- in card script
put empty into field \"Search\"
pass closeCard -- give stack script a crack at it
end closeCard
Built-in messages that perform a task, such as keyDown and closeStackRequest, must be received by the engine or the task will not be performed. For example, LiveCode enters a typed character into a field when it receives the keyDown message, and starts closing a stack when it receives the closeStackRequest message. For this reason, if you create a handler for a built-in message that performs a task, make sure to use the pass control structure to ensure that the engine receives the message after the handler is finished with it.
Similarly, if you set a custom property, the setProp trigger must be received by the engine, or the custom property will not be set. This means that if you create a setProp handler to intercept requests to set a custom property, the property is not set unless you include a pass control structure in the setProp handler.
When a handler executes a pass statement, the message is passed to the next object in the message path. If you use the pass...to top form of the pass control structure, the message is passed directly to the engine, without being passed through any other object in the message path.
To halt the current handler without passing the message on through the message path, use the exit control structure instead. To halt the current handler and return a result, use the return control structure instead.
You cannot use the pass command to pass a message that was originally sent with the send command.
Parameters
| Name | Type | Description |
|---|---|---|
messageName | The name of the handler in which the pass control structure appears. |
Related
message: closeCard, closeStackRequest, keyDown
property: dynamicPaths, backgroundBehavior
constant: return
control structure: pass, exit, setProp, if
glossary: pass, engine, built-in message, property, statement, execute, command, control structure, trigger, custom property, message path, field, message, script, handler, object
Compatibility and Support
Introduced
LiveCode 1.0
OS
mac
windows
linux
ios
android
Platforms
desktop
server
mobile